\label{ch:interfaces}

The CyberOrgs-MMOG implementation provides application programming interfaces for creating cyberorgs, and allows encapsulation of resources and computations. Moreover, the API facilitates resource coordination between computations in an open market of resources. The API offers an interface for the game developers to customize load balancing operations and allows them to exercise fine-grained control on the distribution of zones. In the following sections, these interfaces are discussed in detail. Most of these interfaces, implemented as methods encapsulated in actors can be accessed by sending messages to the appropriate actors. Actors can be extended to employ resource coordination mechanisms based on the game experience. These are discussed in this chapter to demonstrate the flexibility CyberOrgs-MMOG API offers for coordinating resources.

\section {APIs for cyberorgs creation and primitives}

Like a CyberOrgs platform, a CyberOrgs-MMOG platform supports two types of creation: cyberorg creation and actor creation. The first cyberorg (root cyberorg) is created at the startup of the platform. It can also be created using the available graphical user interface or from a user program. Subsequent cyberorg creations result from invocation of the \emph{isolate} primitive. Actor creation can be triggered by other actors in a platform or a \emph{facilitator} actor in case of a cyberorg. A \emph{facilitator} actor is a special actor that performs administrative tasks for a cyberorg \cite{cyber}. The administrative tasks include invoking CyberOrgs primitives such as creation of a new cyberorg, migration of a cyberorg and assimilate to a parent cyberorg. Parameters that are used to make a load management decision- such as response time and bandwidth- can be configured through a configuration file, which the developer may use to enforce certain performance goals.
\\
\\
\textbf{CyberOrg creation :}
\begin{verbatim}
CyberOrg createCyberOrg(long ticks, long ticksrate, long eCash, 
String facilitatorClass, Object[] args)
\end{verbatim}
where \emph{ticksrate} is the rate of processor time that the new cyberorg would receive with respect to the cyberorg in one scheduling cycle; \emph{eCash} is the number of eCash units that are used for buying
processor resource from host cyberorg; \emph{facilitatorClass} and \emph{args} identify the facilitator actor class for the cyberorg and the arguments for creating such a facilitator actor.\\
\\
\textbf{Actor creation:}
\\
Each actor in the CyberOrgs-MMOG platform represents a computation. Actors can be created either by another actor or a cyberorg. Both of the variations are discussed below:
\begin{itemize}
\item 
\begin{verbatim}
ActorName createActor(ActorName creator, String actorClass, 
Object[] args)
\end{verbatim}
where \emph{creator} is the unique actor name of the creator; \emph{actorClass} and \emph{args} specify the class of the actor being created and the arguments used in the actor constructor. This method is used by one actor to create another actor.
\item
\begin{verbatim}
ActorName createActor(CyberOrg host, String facilitatorClass,  
Object[] args)
\end{verbatim}
where \emph{host} identifies the creating cyberorg; \emph{facilitatorClass} identifies the actor class of the facilitator and \emph{args} specify the arguments to be used in constructing the facilitator actor. This is used by the cyberorg constructor at the time of cyberorg creation.
\end{itemize}
\textbf{CyberOrgs Primitives:}\\
Primitive operations are called by the facilitator actor of a cyberorg. 
\begin{itemize}
\item 
\textbf{Isolation:}
\begin{verbatim}
CyberOrg isolate(long eCash, ActorName[] actors, Contract newContract)
\end{verbatim}
where \emph{eCash} is the amount of eCash that is given to the newly created cyberorg; \emph{actors} is a list of existing actors that will be isolated into the new cyberorg; \emph{newContract} is the contract imposed on the new cyberorg and its host cyberorg, which specifies the ticks, ticks rate of processor as well as total length of data and data rate (for network resource control) that the new cyberorg receives, as well as the cost of the resources in terms of eCash payments to be made.
\item
\textbf{Assimilation: }
\begin{verbatim}
CyberOrg assimilate() 
\end{verbatim}
This primitive will cause assimilation of the cyberorg into its host. Invocation of this primitive results in releasing all resources, eCash and computations to the parent cyberorg.
\item
\textbf{Migration:}
\begin{verbatim}
void migrate(ActorName facActorOfDestCyberOrg, Contract newContract)
\end{verbatim}
where \emph{facActorofDestCyberOrg} is the name of facilitator actor in the destination cyberorg, which serves as the cyberorg's name; \emph{newContract} is the negotiated contract between the migrating cyberorg and the intended host. 
\end{itemize}
\textbf{Negotiation}\\
Every migration starts with a negotiation between a cyberorg and a prospective host cyberorg. The negotiation is invoked by the facilitator actor of the migrating cyberorg.
\begin{verbatim}
Contract negotiate(ActorName destFacilitatorActor)
\end{verbatim}
Here \emph{destFacilitatorActor} is the facilitator actor of the prospective future host CyberOrg. A \emph{Contract} object holds 3 attributes -

\begin{itemize}
\item{\emph{Ticks}}- The amount of resources that are given to the child cyberorg in one scheduler cycle.
\item \emph{Ticksrate}- The rate of resources that the child cyberorg would get with respect to the root cyberorg.
\item \emph{Price}- The virtual price of the resource in terms of \emph{eCash}.
\end{itemize}

\section{API for Resource Owner}

The following invocations allow registering and deregistering of potential cyberorgs that have available resources :
\begin{verbatim} 
void register(CyberOrgTuple p_ctTuple) 
void deregister(CyberOrgTuple p_ctTuple)
\end{verbatim}
Here \emph{p\_ctTuple} is an instance of CyberOrgTuple that encapsulates necessary information such as the IP address, associated contract and the facilitator actor of a cyberorg. A resource owner can send a request to register its resources to CyberOrg Directory Manager through a broker. A Broker provides ``registerToCDM'' method for this purpose. 
\begin{verbatim}
void registerToCDM(CyberOrgTuple cyberOrgTuple, ActorName sender)
\end{verbatim}
Here, \emph{sender} is the name of the actor that sends the message on behalf of a resource owner; \emph{cyberOrgTuple} encapsulates the information required to access the resource.

\section{API for Game Owner}
Game owners are the publishers or developers of the game. Initially, a game owner sends a request to a broker to find out what are the potential resources available. the broker receives this request, in response it returns a list of cyberorgs that are currently registered in CDM. Upon receiving this list, a game owner proposes a contract to each of the cyberorg from the list and keeps doing this until a successful negotiation is made. Once a contract is signed, the cyberorg is inserted into GDM and removed from CDM. Following are the interfaces provided by a broker to facilitate these services.
\begin{verbatim}
void getNewResource(Contract contract, String gameName, 
ActorName sender)
\end{verbatim}
Here, \emph{contract} represents the search criteria for potential resources; \emph{gameName} is the name of the game and \emph{sender} represents the actor responsible for making requests on behalf of a game owner.
\begin{verbatim}
void negotiate(CyberOrgTuple cyberOrgTuple, Contract contract, 
ActorName sender)
\end{verbatim}
This method provides an interface to the negotiation process. Here, \emph{cyberOrgTuple}  identifies the potential resource with a proposed \emph{contract}.
\begin{verbatim}
void registerToGDM(CyberOrgTuple cyberOrgTuple)
\end{verbatim}
This method registers a cyberorg, identified by \emph{cyberOrgTuple} with additional game related information into the GDM.

\section{API for Game Player}

A game player initially requests a broker for the available games that are provided by different game owners. The broker then searches in the GDM for resource that matches the price tag mentioned in the contract. This search result is presented to the player as a list of games. Once a game is chosen, a list of available hosts is presented. Now game player can select a particular host from this list and get connected to the chosen host. During this connection phase, the player pays the respective game owner. Following interfaces are provided to a player.

\begin{verbatim}
void getGameList(Contract contract, ActorName sender)
\end{verbatim}
This method searches for appropriate games according to the \emph{contract} where \emph{sender} represents the player actor. The contract object facilitates controlling of game experience by controlling the resources it consumes.
\begin{verbatim}
Object[] getServerList(String gameName, Contract contract) 
\end{verbatim}
This method returns a list of available servers for a particular \emph{gameName} according to the specified \emph{contract}.

\section{APIs for Zone Division and Load Management}
This part of the API provides interfaces to access and update zone related information such as population of the zone, size of the zone etc. It also consists of an algorithm to divide zones in smaller sub-zones. This algorithm currently creates rectangular zones. Developers can implement their own algorithm based on their needs. These methods are implemented in a static class \texttt{ZoneDivider}. In this section, some of these interfaces are discussed.

\begin{verbatim}
ZoneBox createZoneBox(String zoneName, String ip, int x, int y, 
int width, int height)
\end{verbatim}
This method creates a \texttt{ZoneBox} object, which stores metadata of a zone such as size, IP address of the cyberorg encapsulating a zone. \emph{zoneName} represents the name of the zone, where \emph{x}, \emph{y}, \emph{width} and \emph{height} represents the rectangle that defines the size of the zone. IP address can be obtained as an available resource by accessing broker services. It should be noted that the ZoneBox class does not represent the actual zone. It comprises of data and methods required by the zone division algorithm.
\begin{verbatim}
void incrementPopulation(RPObject rPObject)
\end{verbatim}
This method allows updating the population of the zone and is called when a new player joins a zone. This event is detected by an actor that keeps track of the changes occurring in every turn. Here, \emph{rPObject} is an instance of RPObject representing the new player entity.
\begin{verbatim}
void divideZoneStrategy()
\end{verbatim}
This method defines the zone division strategy. The cutoff performance paramenters such as population limit, bandwidth and response time can be defined in the configuration file. In the following section the format of the configuration file is shown. 
\begin{verbatim}
void resetPopulation()
\end{verbatim}
The population of a zone can be reset to zero by invoking this method. This is mostly used during a new zone creation.

Moreover, \texttt{ZoneDivider} class implements methods to detect if an entity representing a player is in the region shared by two zones, to define the extension of the boundary of a zone that is replicated from another zone, to identify a player's zone etc. Load Manager detects a load condition by accessing these methods.


\section{Configuration File}
\label{sec:conf}
A file named ``server.ini'' provides easy access to configure the system-wide properties. Following is an example of a typical configuration file. The maximum number of players for each zone can be specified in this file. The parallel connection limit poses a restriction on how many simultaneous connections can be made from the same client machine. For the purpose of simulation, the limit is set to 1000 as most of the players are simulated clients from the same machine. In real world gaming, this has to be set to a much smaller number to prevent flooding or cheating. Zone size defines the number of players in a zone that initiates a load balancing task. Same is the case with repose time cutoff and bandwidth cutoff. However, only one of these parameters can be set.

\begin{Verbatim}[frame=single, samepage=true, label=server.ini]
max_number_of_players=500
parallel_connection_limit=1000
zone_size=150
reponse_time_cutoff=60ms
bandwidth_cutoff=80KB/s
jdbc_url=jdbc:mysql://localhost:3306/marauroa
jdbc_class=com.mysql.jdbc.Driver
jdbc_user=root
jdbc_pwd=123
tcp_port=5555
turn_length=220
\end{Verbatim}

Other properties that can be set are the information to access the database, length of each turn etc.



